home *** CD-ROM | disk | FTP | other *** search
/ Software Vault: The Gold Collection / Software Vault - The Gold Collection (American Databankers) (1993).ISO / cdr03 / wpm4.zip / M4.DOC next >
Text File  |  1993-07-04  |  13KB  |  367 lines
  1.         M4.DOC                     12 November 86           Page 1
  2.  
  3.  
  4.         Copyright 1986  Michael M Rubenstein
  5.  
  6.         M4 is a MSDOS version of the Unix (tm) m4 macro processor.  All
  7.         functions of the Unix version 7 m4 are supported as well as a
  8.         number of extensions.  This version was written without reference
  9.         to the Unix source and should not be expected to match the Unix
  10.         version if used in an undocumented manner.
  11.  
  12.         M4 requires MSDOS or PCDOS version 2.0 or higher.  No particular
  13.         IBM compatibility should be required.
  14.  
  15.  
  16.  
  17.         Usage
  18.  
  19.         M4 is invoked with the command
  20.  
  21.              m4 [<input file>...]
  22.  
  23.         For example, to apply m4 to the files file1.m4 file2 file3.fil,
  24.         the command
  25.  
  26.              m4 file1.m4 file2 file3.fil
  27.  
  28.         is used.  Output is always to stdout, which is usually
  29.         redirected.  If no input files are given, input is taken from
  30.         stdin.  Any of the input files may be specified as -, in which
  31.         case it is taken from stdin.
  32.  
  33.  
  34.  
  35.         Description
  36.  
  37.         M4 reads one or more text files and writes the modified output to
  38.         stdout (which may, of course, be redirected).  When a macro is
  39.         encountered, it is evaluated and the result is rescanned.  Text
  40.         may be quoted by enclosing it in `' (note that these are not the
  41.         same character).  When quoted text is encountered, the quotes are
  42.         removed and the text is not scanned for macros.  However, if the
  43.         text is used in a macro evaluation and is rescanned, macro
  44.         substitution will take place.  Quotes may be nested to allow text
  45.         to be rescanned several times without evaluation.
  46.  
  47.         The "define" built in macro permits definition of new macros.
  48.         For example
  49.  
  50.              define(A, 3)
  51.  
  52.         defines A to be 3.  No space is permitted between the macro name,
  53.         "define", and the left parenthesis.  If a macro name is not
  54.         followed immediately by a left parenthesis, it has no arguments.
  55.  
  56.         Macro names consist of letters, underscores, and digits and must
  57.         begin with a letter or underscore.  Case is significant.  Macro
  58.         names are recognized only when they appear as words (i.e.,
  59.  
  60.  
  61.                                     1
  62.         M4.DOC                     12 November 86           Page 2
  63.  
  64.  
  65.         surrounded by characters which may not appear in a macro name).
  66.  
  67.         Macros are expanded at the earliest opportunity.  Therefore, the
  68.         sequence
  69.  
  70.              define(A, 3)
  71.              define(B, A)
  72.  
  73.         would define A and B as 3.  However, since the "A" in the second
  74.         line is replaced by 3 before definition takes place, changing the
  75.         value of A will not affect B.  If the order of the definitions
  76.         were changed to
  77.  
  78.              define(B, A)
  79.              define(A, 3)
  80.  
  81.         the value of B would change with that of A (actually, B would be
  82.         replaced by A which would then be replaced by it's value, 2).
  83.  
  84.         Alternatively, one could
  85.  
  86.              define(A, 3)
  87.              define(B, `A')
  88.  
  89.         The quotes prevent A from being evaluated in the second line, so
  90.         B is again defined as A.  In general, quoting the second argument
  91.         of "define" is useful to prevent evaluation before definition.
  92.  
  93.         M4 always strips off one level of quotes when it evaluates
  94.         something.  Thus, if one wishes to use the word "define" in the
  95.         text, it must be quoted.
  96.  
  97.              int `define';
  98.  
  99.         will be changed to
  100.  
  101.              int define;
  102.  
  103.         by M4.
  104.  
  105.         Quoting is necessary when redefining a macro.  For example, the
  106.         sequence
  107.  
  108.              define(A, 2)
  109.              define(A, 3)
  110.  
  111.         would leave A defined as 2 since the second line would expand to
  112.  
  113.              define(2, 3)
  114.  
  115.         The proper sequence is
  116.  
  117.              define(A, 2)
  118.              define(`A', 3)
  119.  
  120.  
  121.  
  122.                                     2
  123.         M4.DOC                     12 November 86           Page 3
  124.  
  125.  
  126.         Macros may have arguments.  The definition
  127.  
  128.              define(sum, `($1 + $2)')
  129.  
  130.         could be used to generate code to add two numbers.  For example,
  131.  
  132.              sum(a, 3)
  133.  
  134.         would generate
  135.  
  136.              (a + 3)
  137.  
  138.         Omitted arguments are replaced by a null string, so
  139.  
  140.              sum(a)
  141.  
  142.         would generate
  143.  
  144.              (a +)
  145.  
  146.         Excess arguments are ignored.
  147.  
  148.         A macro may use up to 9 arguments, $1, $2, ..., $9.  $0 is the
  149.         name of the macro.
  150.  
  151.         Software Tools (B. W. Kernighan and P. J. Plauger, Addison-
  152.         Wesley, Inc., 1976) contains a similar macro processor and much
  153.         more extensive discussion of it's usage.
  154.  
  155.  
  156.  
  157.         Built In Macros
  158.  
  159.         aquote(<leftquote>,<rightquote>,...)
  160.              Defines up to 4 pairs of alternate quotes.  Alternate quotes
  161.              prevent scanning for macros, but, unlike regular quotes, are
  162.              not removed from the text.  Default is no alternate quotes.
  163.              This is an extension in this version of M4.  It's primary
  164.              purpose is to prevent evaluation of macros in strings of a
  165.              language being preprocessed.
  166.  
  167.         changequote(<leftquote>, <rightquote>)
  168.              Changes the quote characters.  Default quotes are `'.
  169.  
  170.         changarg(<character>)
  171.              Changes the argument flag character (default "$").  Note
  172.              that the argument flag character is processed at expansion
  173.              time, not at definition time.  This can lead to strange
  174.              results if this macro appears after any definitions.
  175.  
  176.         comment(<character>)
  177.              Changes the comment character (default #).  All input
  178.              from a comment character to the end of the line is simply
  179.              passed to the output.  If no argument, there will be no
  180.              comment character.
  181.  
  182.  
  183.                                     3
  184.         M4.DOC                     12 November 86           Page 4
  185.  
  186.  
  187.  
  188.         decr(<integer>)
  189.              <integer> - 1
  190.  
  191.         define(<name>,<value>)
  192.              Defines <name> to as <value>.  Up to 9 arguments may be
  193.              used.  Arguments are referenced in the definition (<value>)
  194.              by preceding a digit (1-9) by a special character (default
  195.              "$").  Argument 0 is the name of the macro.
  196.  
  197.              See also, changearg.
  198.  
  199.         divert(<integer>)
  200.              Sends output to diversion file <integer> if <integer> is
  201.              from 1 to 9.  Restores normal output if <integer> is 0 or
  202.              omitted.  Ignores output if <integer> is outside of the
  203.              range 0 through 9.
  204.  
  205.              Diversions are normally copied to the output in numeric
  206.              order after all input.  This can be modified by undivert
  207.              (q.v.).
  208.  
  209.         divnum
  210.              The number of the currently active diversion.  0 if no
  211.              diversion.
  212.  
  213.         dnl
  214.              Deletes all characters through the next newline.  This is
  215.              useful for preventing excess new lines from being translated
  216.              during definition.  For example, the sequence
  217.  
  218.                   define(A, something)
  219.                   define(B, somethingelse)
  220.  
  221.              will be translated into two new lines.  By adding "dnl" to
  222.              the end of each line, this can be prevented.
  223.  
  224.         dumpdef(<name1>,<name2>,...)
  225.              Displays the definitions of <name1>, etc. on stderr.  For
  226.              obvious reasons, <name1>, etc. should usually be quoted.  If
  227.              there are no arguments, all definitions are displayed.
  228.  
  229.         errprint(<format>,<string1>,...,<string8>)
  230.              Prints to stderr.  <format> is as in C fprintf.  This will
  231.              not be meaningful if <format> contains any non-string format
  232.              codes.
  233.  
  234.         eval(<expression>)
  235.              The evaluation of the integer expression <expression>.
  236.              Permitted operators in decreasing order of precedence are
  237.  
  238.                   + (unary), - (unary)
  239.                   *, /, %
  240.                   + (binary), - (binary)
  241.                   ==, !=, <, <=, >, >=
  242.  
  243.  
  244.                                     4
  245.         M4.DOC                     12 November 86           Page 5
  246.  
  247.  
  248.                   !
  249.                   & or &&
  250.                   | or ||
  251.  
  252.              Note that "&" and "&&" are equivalent, as are "|" and "||".
  253.              "a && b" gives 1 if both a and b are nonzero, 0 otherwise.
  254.              "a || b" gives 1 if either a or b is nonzero, 1 otherwise.
  255.              Unlike the similar C expressions, however, evaluation is not
  256.              stopped once the value can be determined.
  257.  
  258.  
  259.         ifdef(<name>,<value1>,<value2>)
  260.              If <name> is defined then <value1> else <value2>.  For
  261.              obvious reasons, <name> should usually be quoted.
  262.  
  263.         ifelse(<str1>,<str2>,<value1>,<value2>)
  264.              If <str1>=<str2> then <value1> else <value2>.
  265.  
  266.              <value2> can be replaced by <str3>,<str4>,<valu3>,<value4>,
  267.              in which case the result is
  268.  
  269.                   if <str1>=<str2> then <value1>
  270.                   else if <str3>=<str4> then <value3>
  271.                        else <value4>
  272.  
  273.              This can be extended in the obvious manner.
  274.  
  275.         include(<filename>)
  276.              The contents of the file <filename>.  It is an error for
  277.              <filename> not to  exist.  See also sinclude.
  278.  
  279.         incr(<integer>)
  280.              <integer> + 1
  281.  
  282.         index(<string1>,<string2>)
  283.              The position (origin 0) in <string1> where <string2> begins.
  284.              -1 if <string2> does not occur in <string1>.
  285.  
  286.         len(<string>)
  287.              The length of <string>.
  288.  
  289.         macro(<character>)
  290.              Defines the macro character.  Macros will only be recognized
  291.              if preceded by the macro character.  Note that this only
  292.              applies to macro invocations.  The macro character is not
  293.              used in the definition of a macro.  If no argument, macros
  294.              will always be recognized.  For example, to define `this' as
  295.              `that' when the macro character is &, the definition would
  296.              be
  297.  
  298.                   &define(`this', `that')
  299.  
  300.              "&this" would be changed to "that", but "this" would be
  301.              unchanged.
  302.  
  303.  
  304.  
  305.                                     5
  306.         M4.DOC                     12 November 86           Page 6
  307.  
  308.  
  309.         mktemp(<string>)
  310.              Generates a unique filename.  String should contain a
  311.              substring of several "X"s which are changed in such a way
  312.              the result is a unique file name.
  313.  
  314.         msdos
  315.              Defined as null.  The Unix version defines "unix" as null,
  316.              so a macro script can determine the operating environment.
  317.  
  318.         nobuiltin
  319.              Removes the definitions of all built in macros.  Deletes all
  320.              characters through the next newline.
  321.  
  322.              This is an extension in this version of M4 to facilitate use
  323.              as a preprocessor.
  324.  
  325.         sinclude(<filename>)
  326.              The contents of the file <filename>.  If <filename> does not
  327.              exist, null.  See also include.
  328.  
  329.         substr(<string>,<start>,<length>)
  330.              The substring of <string> starting at position <start>
  331.              (origin 0) and length <length>.  If <length> is omitted, the
  332.              result is the rest of the string.
  333.  
  334.         syscmd(<string>)
  335.              The operating system command <string> is executed.
  336.  
  337.         translit(<string1>,<string2>,<string3>)
  338.              <string1> with characters in <string2> replaced by the
  339.              corresponding characters in <string3>.  If <string3> is
  340.              shorter than <string2>, characters without an entry in
  341.              <string3> are deleted.
  342.  
  343.         undefine(<name>)
  344.              Removes the definition of <name>.  For obvious reasons,
  345.              <name> should usually be quoted.
  346.  
  347.         undivert(<integer>)
  348.              Copies (and empties) diversion <integer>.  If <integer> is
  349.              omitted, all diversions are copied.  The diversions are not
  350.              rescanned for macros.
  351.  
  352.  
  353.  
  354.         For the Hacker
  355.  
  356.         Source code is provided.  M4 was compiled with Aztec C, but it
  357.         should be very easy to modify for other C compilers.
  358.  
  359.  
  360.  
  361.  
  362.  
  363.  
  364.  
  365.  
  366.                                     6
  367.